VSInterp Scripting Reference - Versus Jesse McGrew From a scripter's perspective, the Versus language can be divided into four parts: evaluating variable and function references in text; evaluating numerical expressions; running commands; and processing loops and statements. Evaluating Variable and Function References (ParseVars) ======================================================= Strings of text are often evaluated to expand embedded references and substitutions. This process has two parts. First, backslash substitutions are performed, which map a backslash followed by a letter into a single ASCII character: \A CTCP delimiter (^A, ASCII 1) \L newline or BIRC hyperlink character (^J, ASCII 10) \S carriage return or BIRC script link character (^M, ASCII 13) \b bold (^B, ASCII 2) \k color (^C, ASCII 3) \t tab (^I, ASCII 9) \o normal (^O, ASCII 15) \r reverse (^R, ASCII 18) \i italic (^V, ASCII 22) \u underline (^_, ASCII 31) Next, dollar sign references (functions and variables) are expanded. These references are possible: $$ changes to a single dollar sign. $0 through $9 changes to the value of the named pseudovariable. $0- through $9- changes to the value of the named pseudovariable list. $5- is the same as $5 $6-, or $5 $6 $7-, etc. $9- contains $9 and any words following it. $varname changes to the value of the named variable. variable names are case-sensitive. if there is no variable by that name, it will remain unchanged. the parser picks the longest matching variable name: for example, if there is a variable named $foo but none named $food, "$food" will evaluate to the value of $foo followed by the letter "d". $'$varname' changes to the value of the variable whose name is in the named variable. for example, if $varname contains "foo", $'$varname' will return the value of $foo. ${text} recursively evaluates the text, then changes to the value of the variable with that name. for example, if $varname contains "5", ${foo$varname} will return the value of $foo5. $arrayname.text recursively evaluates the text, then changes to the value of the variable whose name is arrayname followed by a dot and the result of the evaluation. for example, if $varname contains "5", $foo.$varname will return the value of $foo.5. $funcname(text) recursively evaluates the text, runs the named function (giving the text as parameters), and changes to the function's return value. if there is no function by that name, or if the function is an alias that returns no value, the return value will be "". $(text) interprets the text as a numerical expression (see the next section). $?="message|default value" this is the input box pseudofunction. it displays a dialog box with the message in the window and an input line where the user can type text. if the vertical bar and default value are omitted, the input line will be empty; otherwise, it will contain the default value. the pseufunction reference is then changed into the text typed on the input line, or the string "INPUT_CANCELLED" if the user cancelled by pushing Escape or Cancel. if the same pseudofunction reference appears more than once in the text (with the same message and default value), the box will only be displayed once. The variable $null is predefined to equal an empty string. In addition, $scriptdialect is predefined to the string "Versus", and $scripthost is a string describing the application running the script. Evaluating Numerical Expressions ================================ Numerical expressions are used as conditions in loops and by the $() construct. These are standard algebraic expressions, with the following operators in order from lowest to highest precedence (operators on the same line have equal precedence): !! && boolean or, and == != <= >= < > equals, does-not-equal, less-or-equal, greater-or-equal, less-than, greater-than + - add, subtract * / % multiply, divide, remainder | & ^ bitwise or, and, xor << >> bitwise shift left, shift right ^^ exponent ~ - ! [unary] bitwise not, arithmetic negation, boolean not For example, -5*4+2 will be evaluated as ((-5)*4)+2, or -18. Boolean and comparison operators return 0 (false) or 1 (true). All binary operators are left-associative: 1-2-3 is evaluated as (1-2)-3. Strings can also be compared by enclosing them in [square brackets]: [a] == [b] check for equality, ignoring case [a] === [b] check for equality, matching case [a] != [b] check for inequality, ignoring case [a] !== [b] check for inequality, matching case [a] < [b] does "a" come before "b", ignoring case? [a] <= [b] does "a" come at or before "b", ignoring case? [a] > [b] does "a" come after "b", ignoring case? [a] >= [b] does "a" come at or after "b", ignoring case? When a numerical expression is used as a condition, any nonzero value is true and zero is false. Numbers can be specified as either signed decimal integers (123, -500, etc.) or unsigned hexadecimal numbers prefixed with a dollar sign ($FF, $20, etc.). Since the dollar sign also introduces a variable reference, the dollar sign before a hex number should be doubled to prevent unwanted evaluations: $$FF + $$1 Running Commands ================ A command is a line of text that describes an action to be performed without altering the flow of execution. Commands can be prefixed with the characters ^ and/or * (in that order), which suppress text output and alias matching respectively. Command names are case-insensitive. Commands are described in the reference table at the end of this document. Normally a command is evaluated before it is run. In addition to commands described in the table, these special forms are also available, and are not evaluated before they are run: $varname++ increments the value of $varname by 1. $varname-- decrements the value of $varname by 1. $varname += num increments the value of $varname by , which must be an integer constant. $varname -= num decrements the value of $varname by . @ $varname = text evaluates the text, then assigns it to the global variable $varname. this value of $varname will be available in every alias, event, and menu item. $varname can also be of the form $arrayname.text as described in the first section. @s $varname = text same as above, but this value will be stored so that it's still available the next time the program is run. -@ $varname deletes the global variable $varname. -@s $varname deletes the global variable $varname and removes it from storage so that it won't be back next time the program is run. @l $varname = text (that's the letter L as in Local) evaluates the text, then assigns it to the local variable $varname. this value of $varname will only be available in the current alias, event, or menu item, and it will mask out any global variable by that name as long as it exists. There is no -@l because local variables are automatically deleted when their enclosing routine exits. Processing Loops and Statements =============================== Loops and statements are constructs that span more than one line or alter the flow of execution. They may contain commands, and a command is always permitted wherever a loop or statement is, but a loop or statement isn't permitted everywhere that a command is. The first line of a loop or statement can always be prefixed with 'Eval' to cause it to be evaluated. Break [if ] Exits the innermost loop. If a condition is specified, the loop is only exited when the condition is true. Continue [if ] Skips the rest of the code in the innermost loop and runs through the loop again. If the loop has an increment part ('for' and 'foreach'), it will be run before the next iteration of the loop. If a condition is specified, the loop is only exited when the condition is true. Halt [if ] Exits immediately from the current alias, event, or menu item. If a condition is specified, the routine is only exited when the condition is true. Alias [] EndAlias Creates an alias with the given name, hotkey, and code (the host application may not support hotkeys). The alias can be called just like a command or function: parameters will be broken into words and passed in as $1 through $9. $1- contains $1 and all the words after it, and so on. $0 contains the name of the alias as it was called; the first character of $0 will be % if it was called as a function. If the alias is a function, it can return a value by assigning it to the global variable $fresult. The variable's value will not be overwritten by intervening function calls; it will be saved before a function call and restored afterward. Event "" EndEvent Creates an event with the given name, mask, and code. The event will be called by the host application when it sees fit (typically when some kind of application-specific event happens that is described by ). The host application may not support events. Parse [extended] EndParse Breaks up into words, assigns them to the pseudovariables $0 through $9 (and $0- through $9-), and runs with the modified pseudovariables. If the 'extended' keyword is specified, the text will be split up like list elements instead of simple words (see the section later about list functions). If [ElseIf ] [Else ] EndIf Executes if the condition is true. If one or more ElseIf sections are given and the condition is false, flow of execution will proceed to the first section whose condition is true, skipping the rest of the sections. If none of the conditions are true and an Else section is specified, it will be run. While [optimized] EndWhile Executes repeatedly as long as the condition is true. If the condition is initially false, the code will never be run. If the 'optimized' keyword is specified and is a single line, it will be run as a command without evaluation (instead of a block of commands and statements), which is faster. If the command needs to be evaluated, prefix it with 'Eval'. For [optimized] (; ; ) EndFor Runs , then executed repeatedly as long as the condition is true, running after each iteration. If 'Continue' is executed in the code, will still be run before the next iteration. If the condition is initially false, the code will never be run. The 'optimized' keyword works just like in 'While'. ForEach (; ) EndForEach Breaks up into list elements, then locally assigns them in turn to each member of (which must be a comma-separated list of one or more variable names) and runs , repeating until all the list elements have been used. Some of the variables will be empty during the last iteration if there are not enough list elements to fill them. Switch [case : ] [case multi ] [case range .. ] [case is ] [case matches ] [case expr ] [case else ] EndSwitch Evaluates , locally assigns the result to $@, then executes the code for the first case clause that matches. A case clause of the first type matches if its text is the same as $@, ignoring case. A 'case multi' matches if any one of the (which must be a comma-separated list) is the same as $@, ignoring case. A 'case range' matches if $@ is a number between and , inclusive. A 'case is' matches if $@ is a number that obeys the given relation (for example, 'case is < 100' would match when $@ is a number less than 100). A 'case matches' matches when $@ is matched by the given wildcard pattern (see $WildMatch() in the function reference). A 'case expr' matches when the expression evaluates to true. A 'case else' matches when no other cases have matched. There may be only one 'case else', but the other case clauses can occur any number of times in any order. MenuTree EndMenuTree Creates a menu tree with the given name and description. The interpretation of and is up to the host application, which might not support menus at all. MenuItem on EndMenuTree Assigns code to a menu item that was previously created by MenuTree. The host application may not support menus. Language EndLanguage Runs through the ActiveScripting engine specified by . The foreign code has access to an object called 'Versus' with the following methods: Parse(Text: string): string Evaluates Text and returns the result. GetVar(Name: string): string Returns the value of the variable with the given name. Execute(Command: string) Evaluates the command, then runs it. ExecuteNoEval(Command: string) Runs the command without evaluating it. SetVar(Name, Value: string) Sets the named global variable to the given value. SetVarLocal(Name, Value: string) Sets the named local variable to the given value. The variable is local to the alias/event/menuitem containing the Language statement. IncVar(Name: string; Amount: integer) Adds the given amount to the value of the named variable. ... and the following property: State: integer (read-only) Contains an integer made by adding together 1 if the enclosing alias, event, or menu item was called as a function, and 2 if text output is being suppressed. With EndWith Prefixes to each line of (without an intervening space), then runs the code. Function Reference ================== TVSInterp's commands are divided into separate groups, which can be individually enabled or disabled by the host application: Set Functions ------------- A set is a comma-separated list of words surrounded by square brackets: [alpha,beta,zappa]. Whitespace, case, and duplicate elements are ignored; that set is equivalent to [Alpha, Beta ,ZapPa]. The empty set is []. $AddToSet( ) Returns after cleaning it up and adding all the items from (which can be a set or a comma-separated list of items). The list returned has no space between items, no duplicate items, and is all lowercase. $RemoveFromSet( ) Returns after cleaning it up and removing all the from it. $IsInSet( ) Returns 1 (true) if all the items from appear in , or 0 (false) otherwise. can be a set or a comma-separated list of one or more items. List Functions -------------- A list is a group of list elements separated by spaces. Each item can take one of three forms: 1. A single word, e.g.: foo 2. One or more words enclosed in double quotes, e.g.: "foo bar" 3. Any text enclosed in balanced angle brackets, e.g.: > Elements of type 1 and 2 may contain other characters escaped inside them using backslashes: "\"Hello,\" he said." Functions that return a single element strip the quoting before returning it. Each list element has a numerical index, starting with zero for the first element. When a list function expects a pattern or delimiter as a parameter, the parameter can be quoted into a list item (see $ListQuote()) if it contains spaces or quote marks. $ListClean() Returns the list with multiple spaces between items condensed into a single space. $ListDelete( ) Returns the list after removing the th element. $ListElementCount() Returns the number of elements in the list. $ListFromWords() Creates a list that contains each word in as an element in order and returns it. This is equivalent to $ListSplit(" " ). Use this before attempting to use list functions or ForEach on a list of words that have not been quoted as list elements but might contain special list characters such as backslash. $ListIndex( ) Extracts the th element from the list and returns it. The return value is empty if there is no element with that number. $ListIndexOf( ) Returns the index of the first element in the list that matches the pattern. $ListInsert( ) Returns the list after inserting at the th position. If is greater than the number of elements in the list, blank elements will be inserted at the end before . $ListJoin( ) Concatenates the list's elements by adding in between. Any list quoting around the elements will be stripped, so joining the elements with a space will not necessarily produce the same list. $ListQuote() Returns quoted into a suitable list item. Valid type 3 (angle bracket) list items are simply surrounded with another pair of angle brackets; other types are scanned through to escape list markers with backslashes, then surrounded with double quotes if they contain spaces. $ListRand() Returns a random element from the list. $ListRange( ) Returns the list created by extracting elements numbered through (inclusive) from . $ListRemove( ) Returns the list after removing all elements that match . $ListReplace( ) Returns the list after removing all elements from to (inclusive) and replacing them with the single element . $ListSearch( ) Returns the list created by extracting all the elements that match from $ListSearchReplace( ) Returns the list after replacing all elements that match with . $ListShuffle() Returns the list with the elements rearranged in a random order. $ListSort() Returns the list after sorting the elements in ASCII order. $ListSplit( ) Returns the list created by splitting into elements separated by . Miscellaneous Functions ----------------------- Functions that deal with character positions number the characters starting at 1 for the first character. $Asc() Returns the ASCII code of the first character of the text. $Char() Returns the character with the given ASCII number. $CTime() Returns the number of seconds Windows has been running. $Date() Returns the current date in a short format. $DecodeInterval() Returns the number of seconds as a human-readable string. For example, $DecodeInterval(3680) returns "1 hour 1 minute 20 seconds". $DecodeMInterval() Returns the number of milliseconds as a human-readable string. For example, $DecodeMInterval(3680711) returns "1 hour 1 minute 20.711 seconds". $Eval() Evaluates an additional time, then returns it. $GlobMatch( ) Attempts to match against , using only classic wildcards, and returns true if it succeeds. may contain spaces, but may not. Classic wildcard patterns can contain the following special characters: ? matches exactly one character of any value * matches zero or more characters of any value All other characters are compared directly against the text, ignoring case. For example, the pattern "f?o" would match "foo" or "f o" or "flo" but not "floo". $GlobMatchCase( ) Same as $GlobMatch(), but case-sensitive. $IsNumeric() Returns true if the text is an integer. Note that this will return true even for numbers that are out of range. $Length() Returns the number of characters in the text. $Lower() Returns the text converted to lowercase. $MTime() Returns the number of milliseconds Windows has been running. $NoAttribs() Returns after changing all characters produced by backslash substitutions back to the original text. For example, $NoAttribs(c:\temp) returns "c:\temp", even though the \t is originally interpreted as a tab. $Rand() Returns a random number greater than or equal to zero, and less than . If is omitted, it is assumed to be 2. $RStrPos( ) Returns the position of the beginning of the rightmost occurrence of in , or 0 if it doesn't appear. $RStrTokL( ) Searches for the rightmost occurrence of in and returns everything to the left. If does not appear in , this function (and all StrTok functions) pretend that it appears after the end of the text. In that case, this function returns the entire string. $RStrTokR( ) Searches for the rightmost occurrence of and and returns everything to the right. If does not appear in , this function returns an empty string. $StrPos( ) Returns the position of the beginning of the first occurrence of in , or 0 if it doesn't appear. $StrPosFrom( ) Returns the position of the beginning of the first occurrence of in , starting the search at the th character. If does not appear, the function returns 0. $StrTokL( ) Searches for the first occurrence of in and returns everything to the left. If does not appear in , this function returns the entire string. $StrTokR( ) Searches for the first occurrence of in and returns everything to the right. If does not apepar in , this function returns an empty string. $SubStr( ) Copies and returns up to characters from starting at position . If is less than 1 or if is greater than the number of characters in the string, fewer characters than specified will be copied. $Time() Returns the current time in a format specified by . If is omitted, a default short format will be used. The format string may contain the following specifiers: c displays the date and time in the same default format used by $Date() and $Time() without parameters d displays the day of the month without a leading zero (1-31) dd displays the day of the month with a leading zero (01-31) ddd displays the day of the week as an abbreviation (Sun-Sat) dddd displays the day of the week as a full word (Sunday-Saturday) ddddd displays the date in the same default format used by $Date() dddddd displays the date in a default long format m displays the month number without a leading zero (1-12) mm displays the month number with a leading zero (01-12) (if m or mm follow an h or hh, they display the minute instead of the month, as if n or nn were used instead.) mmm displays the month name as an abbreviation (Jan-Dec) mmmm displays the month name as a full word (January-December) yy displays the year as a two-digit number (00-99) yyyy displays the year as a four-digit number (0000-9999) h displays the hour without a leading zero (0-23) hh displays the hour with a leading zero (00-23) n displays the minute without a leading zero (0-59) nn displays the minute with a leading zero (00-59) s displays the second without a leading zero (0-59) ss displays the second with a leading zero (00-59) t displays the time using the same default format as $Time() without parameters tt displays the time using a default long format am/pm displays "am" if it's before noon or "pm" if it's after a/p displays "a" if it's before noon or "p" if it's after (am/pm and a/p can be written in lower, upper, or mixed case, and the displayed string will change accordingly.) ampm displays a language-specific AM or PM specifier (am/pm, a/p, and ampm all force the preceding h or hh specifier to use a 12-hour clock instead of the default 24-hour clock.) / displays a language-specific date separator : displays a language-specific time separator 'x' or "x" text in quotes is displayed as-is, without being formatted as a time string $UnixTime() Returns the current Unix time (number of seconds since midnight, January 1st, 1970 GMT). $UnixTime() Returns the given Unix time formatted in the same format as $Time(c). $UnixTime( ) Returns the given Unix time formatted using the format string, which is interpreted the same way as for $Time(). $Upper() Returns the text converted to uppercase. $WildMatch( ) Attempts to match against and returns true if it succeeds. may contain spaces, but may not. Wildcard patterns can contain the following special characters: ? matches exactly one character of any value * matches zero or more characters of any value % matches zero or more of any character except a space ¬ (ASCII 172) matches either the end of the string, or a space followed by zero or more characters of any value \ escapes the next character so it will not be treated specially All other characters are compared directly against the text, ignoring case. For example, the pattern "f?o" would match "foo" or "f o" or "flo" but not "floo". The pattern "f%o" would match "foo" or "fido" but not "f o". The pattern "foo¬" would match "foo" or "foo " or "foo bar" but not "food". The pattern "how\?" would match "how?" but not "howz". $WildMatchCase( ) Same as $WildMatch(), but case-sensitive. $WordCount() Returns the number of space-separated words that appear in . Miscellaneous Commands ---------------------- Eval Evaluates an additional time, then runs it. NoAttribs Runs the command after changing all characters produced by backslash substitutions back to the original text (as in $NoAttribs()). Note that this will not affect parameters to functions, since the functions have already been called by the time NoAttribs sees the text. To protect function parameters, use $NoAttribs(). Yield Causes the host application to process messages and respond to user input. This command is typically used to prevent a loop from locking up the application. Alias Commands/Functions ------------------------ $AliasExists() Returns true if an alias exists with the given name. UnAlias Removes any alias with the given name. File Commands/Functions ----------------------- IMPORTANT NOTE: Commands and functions that take a filename followed by another parameter expect the filename to be quoted as a list element to preserve spaces. This means that backslashes will be treated specially, and not as path separators. Use $ListQuote() to get around this, e.g.: AppendText $ListQuote($filename) $text Commands and functions that only take a filename do not expect the parameter to be quoted. AppendText Appends as a new line at the end of . Nothing happens if the file does not already exist. ChDir Attempts to change the current directory to the given path. CreateFile Creates an empty file with the given name, or empties the file if it already exists. $DirExists() Returns true if a directory exists with the given name. If no path is given, the current directory is searched. $FileExists() Returns true if a file exists with the given name. If no path is given, the current directory is searched. $GetCurrentDir() Returns the path to the currect directory. $GetFileDateTime( ) Returns the modification time and date of the given file, formatted according to the format string. If is omitted, a default format will be used. If the file does not exist, the result is an empty string. $GetFileSize() Returns the size in bytes of the file, or an empty string if the file does not exist. $GetLinesInFile() Returns the number of lines in the given file, or -1 if the file does not exist. MkDir Attempts to create a directory with the given name. $PathExists() Equivalent to $DirExists(). $RandomRead() Reads a random line from the file and returns it, or returns an empty string if the file does not exist. $ReadLine( ) Returns line number (where the first line is 1) from , or an empty string if the file does not exist or there is no line with that number. RmDir Attempts to delete the named directory. RmFile Attempts to remove the named file. File Dialog Functions --------------------- These functions are only available if both file commands/functions and dialog commands/functions are enabled. The string should be a vertical-bar-separated list of the format: Text files (*.txt)|*.txt|All files (*.*)|*.* where the first segment is a human-readable description of the first file type, the second segment is a file mask for the first type, the third segment is a description of the second file type, and so on. Keep in mind that the filter is only a suggestion, and the dialog will still allow filenames that don't match it. $OpenDialog(|<filter>) Displays a standard Windows file open dialog with <title> in the title bar and <filter> in the drop-down box. Returns the path to the selected file, or an empty string if the user aborts the box by pressing Escape or Cancel. The returned file name is not guaranteed to exist. $OpenPictureDialog(<title>|<filter>) The same as $OpenDialog(), except the dialog will show previews of image files as they are selected. $SaveDialog(<title>|<filter>) Displays a standard Windows file save dialog with <title> in the title bar and <filter> in the drop-down box. Returns the path to the chosen file, or an empty string if the user aborts the box by pressing Escape or Cancel. The dialog will not ask for confirmation if the user selects a file that already exists. $SavePictureDialog(<title>|<filter>) The same as $SaveDialog(), except the dialog will show previews of image files as they are selected. Dialog Commands/Functions ------------------------- MessageBox <text> Displays a message box with an OK button, the application's name in the title bar, and <text> inside the window. $MessageDlg(<format> <text>) Displays a message dialog according to <format> with <text> inside the window, and returns a number describing the user's choice. <format> is a number made by adding these values, at most one from each group: Buttons shown: 0 only show OK button 1 show OK and Cancel 2 show Abort, Retry, and Ignore 3 show Yes, No, and Cancel 4 show Yes and No 5 show Retry and Cancel Icon shown: 16 show STOP icon 32 show question mark icon 48 show exclamation point icon 64 show "i" icon Default button: 0 first button is default 256 second button is default 512 third button is default The return value is a number describing which button was chosen: 1 OK 2 Cancel 3 Abort 4 Retry 5 Ignore 6 Yes 7 No MessageDlg <format> <text> The same as $MessageDlg(<format> <text>) but discards the return value. Sound commands -------------- Beep Plays the default system sound. MCI <command> Sends <command> to Windows's Media Control Interface system. The format of these strings is described in the Win32 API specification. Here are a few more common commands: play <filename> Plays a media file (WAV, MID, AVI). stop <filename> Stops playback and rewinds the file. pause <filename> Pauses playback. resume <filename> Resumes from where the file was paused. record <filename> Begins recording a media file. stop <filename> Stops recording. play cdaudio from <num> Plays track number <num>. stop cdaudio Stops CD playback. Clipboard Command/Function -------------------------- $GetClipboard() Returns the text on the clipboard, or an empty string if there is no text on the clipboard. SetClipboard <text> Sets the clipboard to contain <text>. DDE Command/Function -------------------- $DDE(<service> <topic> <item> <text>) Attempts to send <text> to the specified DDE server using ExecuteMacro, then returns any text that results from it. <item> is treated as a list element, so it may contain spaces. DDE <service> <topic> <item> <text> The same as $DDE(<service> <topic> <item> <text>), but discards any result.